<model>: The HTML Model element

The <model> HTML element represents a three-dimensional (3D) model inline on a web page. On view tracked platforms such as head-mounted devices, this may be presented inside a portal within the page.

A model on an untracked, monoscopic platform: the model appears on the page.

A model on a tracked / stereo platform: the model appears inside the page.

Because a model resource can contain an animation, both the declarative element and the JavaScript API can control aspects of its animated behavior.

It provides a private, declarative method to display three-dimensional model information as an alternative to (and complement for) the JavaScript-based WebXR API.

Coordinate space

A valid model resource will contain three-dimensional data. The coordinate space is interpreted as a right-handed, Y-up coordinate system. That is by default, the model will be displayed with the following alignment:

Y will be displayed as the vertical dimension, with positive-Y directed upward,
X will be displayed as the horizontal dimension, with positive-X directed right,
Z will be displayed as the depth dimension, with negative-Z directed inward.

Note: For safety and security reasons, rendering of content is only permitted inside the portal within the page, and content that protrudes in the +Z dimension beyond the front plane of the page will be clipped.

The coordinate space in a model context

Attributes

This element includes the global attributes.

environmentmap: Defines the URL for the environment map to use to illuminate the model. This resource is assumed to be in an equirectangular projection. A valid environment map may be supplied in any valid image format, but it is recommended to supply a resource capable of presenting raw luminance values, such as OpenEXR .exr format, or RGBE .hdr format.

The projection of the equirectangular back to a sphere

Note: While environment map resources are provided as images, an appropriate resource should contain a very high dynamic range of luminance values, and may not be appropriate to display directly.

autoplay

A Boolean attribute; if specified, the model automatically begins to play back as soon as the model file has been loaded and parsed.

loop

A Boolean attribute; if specified, the browser will automatically seek back to the start upon reaching the end of the model's animation and continue playback.

stagemode

An enumerated attribute indicating which mode, if any, the User Agent should respond to pointer events with by default. It can have the following values:

none, which indicates that the User Agent should take no action,
orbit, which indicates that the User Agent should provide the orbit mode interaction. see stageMode:orbit mode for more in-depth discussion.

src

The model URL to be fetched. Multiple model file candidates may also be provided through one or more source elements for alternate resources, such as the GLTF or USDZ formats.

height

The intrinsic height of the model's viewport, in pixels. Must be an integer without a unit.

width

The intrinsic width of the model's viewport, in pixels. Must be an integer without a unit.

Usage notes

While it provides benefits for all devices and User Agents, the <model> element has particular value on platforms with stereoscopic and/or head-tracking capabilities, such as Head-Mounted Displays (HMDs). It can be used as declarative alternative to the WebXR API to provide spatial content.

Object fit

By default, the model content is initially set to an "object fit". That is, the scale is set such that the model's entityTransform is:

centered horizontally on its boundingBoxCenter.x,
centered vertically on its boundingBoxCenter.y,
scaled uniformly to accommodate its boundingBoxExtents.x inside the viewport's width, and
scaled uniformly to accommodate its boundingBoxExtents.y inside the viewport's height, and
set back to fully display the model's boundingBoxExtents.z within its portal.

This will result in the model being centered inside the viewport and scaled to fit within it:

A model file scaled to the bounds of the viewport specified

Natural scale

While model elements are governed by "object fit" and "orbit fit" transformations by default, model resources have implicit real-world dimensions. For example, A model with its entityTransform set to the identity matrix I₄ with a 10cm teapot will be displayed as occupying 10cm, or approximately 378 CSS pixels in the window.

Note: The CSS-equivalent scale for model contents is unlikely to equate to real-world dimensions on any device. See discussion of CSS units and values for more details.

Examples

In this example, a <model> element is used to portray a teapot.

html

<model alt="a model of a teapot">
  <source src="./teapot.usdz" type="model/vnd.usdz+zip" />
  <source src="./teapot.glb" type="model/gltf+binary" />
  <img src="./teapot-fallback.png" alt="a fallback image of the 3D teapot" />
</model>

The semantics of the model element is that of declaratively portraying a single, three-dimensional object.

Technical summary

Content categories	Flow content, phrasing content, interactive content, palpable content
Permitted content	None; it is a void element.
Tag omission	None, both the starting and ending tag are mandatory.
Permitted parents	Any element that accepts embedded content.
Implicit ARIA role	with non-empty `alt` attribute or no `alt` attribute: `model` with empty `alt` attribute: `presentation`
Permitted ARIA roles	with non-empty `alt` attribute: `button` `checkbox` `link` `menuitem` `menuitemcheckbox` `menuitemradio` `option` `progressbar` `scrollbar` `separator` `slider` `switch` `tab` `treeitem` with empty `alt` attribute, `none` or `presentation` with no `alt` attribute, no `role` permitted
DOM interface	`HTMLModelElement`

Specifications

No specification found

No specification data found for html.elements.model.
Check for problems with this page or contribute a missing spec_url to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.